Asynkron kontextpropagering i JavaScript: Request-spårning och continuation med AsyncLocalStorage

I modern server-side JavaScript-utveckling, särskilt med Node.js, är asynkrona operationer allestädes närvarande. Att hantera tillstånd och kontext över dessa asynkrona gränser kan vara en utmaning. Detta blogginlägg utforskar konceptet med asynkron kontextpropagering, med fokus på hur man använder AsyncLocalStorage för att effektivt uppnå request-spårning och continuation. Vi kommer att undersöka dess fördelar, begränsningar och verkliga tillämpningar, och ge praktiska exempel för att illustrera dess användning.

Förståelse för asynkron kontextpropagering

Asynkron kontextpropagering avser förmågan att bibehålla och propagera kontextinformation (t.ex. request-ID, användarautentiseringsdetaljer, korrelations-ID) över asynkrona operationer. Utan korrekt kontextpropagering blir det svårt att spåra anrop, korrelera loggar och diagnostisera prestandaproblem i distribuerade system.

Traditionella metoder för att hantera kontext förlitar sig ofta på att explicit skicka kontextobjekt genom funktionsanrop, vilket kan leda till mångordig och felbenägen kod. AsyncLocalStorage erbjuder en mer elegant lösning genom att tillhandahålla ett sätt att lagra och hämta kontextdata inom en och samma exekveringskontext, även över asynkrona operationer.

Introduktion till AsyncLocalStorage

AsyncLocalStorage är en inbyggd Node.js-modul (tillgänglig sedan Node.js v14.5.0) som tillhandahåller ett sätt att lagra data som är lokal för livstiden av en asynkron operation. Den skapar i huvudsak ett lagringsutrymme som bevaras över await-anrop, promises och andra asynkrona gränser. Detta gör det möjligt för utvecklare att komma åt och modifiera kontextdata utan att explicit skicka den vidare.

Nyckelfunktioner i AsyncLocalStorage:

• Automatisk kontextpropagering: Värden som lagras i AsyncLocalStorage propageras automatiskt över asynkrona operationer inom samma exekveringskontext.
• Förenklad kod: Minskar behovet av att explicit skicka kontextobjekt genom funktionsanrop.
• Förbättrad observerbarhet: Underlättar request-spårning och korrelation av loggar och mätvärden.
• Trådsäkerhet: Ger trådsäker åtkomst till kontextdata inom den nuvarande exekveringskontexten.

Användningsfall för AsyncLocalStorage

AsyncLocalStorage är värdefull i olika scenarier, inklusive:

• Request-spårning: Tilldela ett unikt ID till varje inkommande request och propagera det genom hela requestens livscykel för spårningsändamål.
• Autentisering och auktorisering: Lagra användarautentiseringsdetaljer (t.ex. användar-ID, roller, behörigheter) för åtkomst till skyddade resurser.
• Loggning och granskning: Bifoga request-specifik metadata till loggmeddelanden för bättre felsökning och granskning.
• Prestandaövervakning: Spåra exekveringstiden för olika komponenter inom en request för prestandaanalys.
• Transaktionshantering: Hantera transaktionstillstånd över flera asynkrona operationer (t.ex. databastransaktioner).

Praktiskt exempel: Request-spårning med AsyncLocalStorage

Låt oss illustrera hur man använder AsyncLocalStorage för request-spårning i en enkel Node.js-applikation. Vi skapar en middleware som tilldelar ett unikt ID till varje inkommande request och gör det tillgängligt under hela requestens livscykel.

Kodexempel

Installera först de nödvändiga paketen (om det behövs):

            npm install uuid express
            

              
                Copy
              
            
          

Här är koden:

            // app.js
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();
const port = 3000;

// Middleware för att tilldela ett request-ID och lagra det i AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simulera en asynkron operation
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Route-hanterare
app.get('/', async (req, res) => {
  const requestId = asyncLocalStorage.getStore().get('requestId');
  console.log(`[Route] Request ID: ${requestId}`);
  await doSomethingAsync();
  res.send(`Hello World! Request ID: ${requestId}`);
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

I det här exemplet:

1. Vi skapar en AsyncLocalStorage-instans.
2. Vi definierar en middleware som tilldelar ett unikt ID till varje inkommande request med hjälp av uuid-biblioteket.
3. Vi använder asyncLocalStorage.run() för att exekvera request-hanteraren inom kontexten av AsyncLocalStorage. Detta säkerställer att alla värden som lagras i AsyncLocalStorage är tillgängliga under hela requestens livscykel.
4. Inuti middleware-funktionen lagrar vi request-ID:t i AsyncLocalStorage med asyncLocalStorage.getStore().set('requestId', requestId).
5. Vi definierar en asynkron funktion doSomethingAsync() som simulerar en asynkron operation och hämtar request-ID:t från AsyncLocalStorage.
6. I route-hanteraren hämtar vi request-ID:t från AsyncLocalStorage och inkluderar det i svaret.

När du kör denna applikation och skickar en förfrågan till http://localhost:3000, kommer du att se request-ID:t loggas både i route-hanteraren och i den asynkrona funktionen, vilket visar att kontexten propageras korrekt.

Förklaring

• AsyncLocalStorage-instans: Vi skapar en instans av AsyncLocalStorage som kommer att hålla vår kontextdata.
• Middleware: Middleware-funktionen fångar upp varje inkommande request. Den genererar ett UUID och använder sedan asyncLocalStorage.run för att exekvera resten av request-hanteringskedjan *inom* kontexten av denna lagring. Detta är avgörande; det säkerställer att allt nedströms har tillgång till den lagrade datan.
• asyncLocalStorage.run(new Map(), ...): Denna metod tar två argument: en ny, tom Map (du kan använda andra datastrukturer om det passar din kontext) och en callback-funktion. Callback-funktionen innehåller koden som ska exekveras inom den asynkrona kontexten. Alla asynkrona operationer som initieras inom denna callback kommer automatiskt att ärva datan som lagras i Map.
• asyncLocalStorage.getStore(): Detta returnerar den Map som skickades till asyncLocalStorage.run. Vi använder den för att lagra och hämta request-ID:t. Om run inte har anropats kommer detta att returnera undefined, vilket är anledningen till att det är viktigt att anropa run inom middleware-funktionen.
• Asynkron funktion: Funktionen doSomethingAsync simulerar en asynkron operation. Avgörande är att även om den är asynkron (med setTimeout), har den fortfarande tillgång till request-ID:t eftersom den körs inom den kontext som etablerats av asyncLocalStorage.run.

Avancerad användning: Kombination med loggningsbibliotek

Att integrera AsyncLocalStorage med loggningsbibliotek (som Winston eller Pino) kan avsevärt förbättra observerbarheten i dina applikationer. Genom att injicera kontextdata (t.ex. request-ID, användar-ID) i loggmeddelanden kan du enkelt korrelera loggar och spåra anrop över olika komponenter.

Exempel med Winston

            // logger.js
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message }) => {
      const requestId = asyncLocalStorage.getStore() ? asyncLocalStorage.getStore().get('requestId') : 'N/A';
      return `${timestamp} [${level}] [${requestId}] ${message}`;
    })
  ),
  transports: [
    new winston.transports.Console()
  ]
});

module.exports = {
  logger,
  asyncLocalStorage
};

            

              
                Copy
              
            
          

            // app.js (modifierad)
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { logger, asyncLocalStorage } = require('./logger');

const app = express();
const port = 3000;

app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    logger.info(`Incoming request: ${req.url}`); // Logga den inkommande requesten
    next();
  });
});

async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      logger.info('Doing something async...');
      resolve();
    }, 50);
  });
}

app.get('/', async (req, res) => {
  logger.info('Handling request...');
  await doSomethingAsync();
  res.send('Hello World!');
});

app.listen(port, () => {
  logger.info(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

I detta exempel:

• Vi skapar en Winston logger-instans och konfigurerar den att inkludera request-ID:t från AsyncLocalStorage i varje loggmeddelande. Nyckeldelen är winston.format.printf, som hämtar request-ID:t (om tillgängligt) från AsyncLocalStorage. Vi kontrollerar om asyncLocalStorage.getStore() existerar för att undvika fel när vi loggar utanför en request-kontext.
• Vi uppdaterar middleware-funktionen för att logga den inkommande requestens URL.
• Vi uppdaterar route-hanteraren och den asynkrona funktionen för att logga meddelanden med den konfigurerade loggern.

Nu kommer alla loggmeddelanden att inkludera request-ID:t, vilket gör det enklare att spåra anrop och korrelera loggar.

Alternativa tillvägagångssätt: cls-hooked och Async Hooks

Innan AsyncLocalStorage blev tillgängligt användes bibliotek som cls-hooked ofta för asynkron kontextpropagering. cls-hooked använder Async Hooks (ett lägre nivåns Node.js API) för att uppnå liknande funktionalitet. Även om cls-hooked fortfarande är vanligt förekommande, föredras AsyncLocalStorage generellt på grund av att det är inbyggt och har bättre prestanda.

Async Hooks (async_hooks)

Async Hooks tillhandahåller ett API på lägre nivå för att spåra livscykeln för asynkrona operationer. Även om AsyncLocalStorage är byggt ovanpå Async Hooks, är det ofta mer komplext och mindre presterande att använda Async Hooks direkt. Async Hooks är mer lämpliga för mycket specifika, avancerade användningsfall där finkornig kontroll över den asynkrona livscykeln krävs. Undvik att använda Async Hooks direkt om det inte är absolut nödvändigt.

Varför föredra AsyncLocalStorage framför cls-hooked?

• Inbyggt: AsyncLocalStorage är en del av Node.js-kärnan, vilket eliminerar behovet av externa beroenden.
• Prestanda: AsyncLocalStorage är generellt mer presterande än cls-hooked på grund av sin optimerade implementering.
• Underhåll: Som en inbyggd modul underhålls AsyncLocalStorage aktivt av Node.js-kärnteamet.

Att tänka på och begränsningar

Även om AsyncLocalStorage är ett kraftfullt verktyg, är det viktigt att vara medveten om dess begränsningar:

• Kontextgränser: AsyncLocalStorage propagerar endast kontext inom samma exekveringskontext. Om du skickar data mellan olika processer eller servrar (t.ex. via meddelandeköer eller gRPC), måste du fortfarande explicit serialisera och deserialisera kontextdatan.
• Minnesläckor: Felaktig användning av AsyncLocalStorage kan potentiellt leda till minnesläckor om kontextdatan inte städas upp korrekt. Se till att du använder asyncLocalStorage.run() korrekt och undvik att lagra stora mängder data i AsyncLocalStorage.
• Komplexitet: Även om AsyncLocalStorage förenklar kontextpropagering, kan det också addera komplexitet till din kod om det inte används försiktigt. Se till att ditt team förstår hur det fungerar och följer bästa praxis.
• Inte en ersättning för globala variabler: AsyncLocalStorage är *inte* en ersättning för globala variabler. Det är specifikt utformat för att propagera kontext inom en enskild request eller transaktion. Överanvändning kan leda till hårt kopplad kod och göra testning svårare.

Bästa praxis för att använda AsyncLocalStorage

För att effektivt använda AsyncLocalStorage, överväg följande bästa praxis:

• Använd Middleware: Använd middleware för att initiera AsyncLocalStorage och lagra kontextdata i början av varje request.
• Lagra minimalt med data: Lagra endast nödvändig kontextdata i AsyncLocalStorage för att minimera minnesanvändningen. Undvik att lagra stora objekt eller känslig information.
• Undvik direktåtkomst: Kapsla in åtkomst till AsyncLocalStorage bakom väldefinierade API:er för att undvika hård koppling och förbättra kodens underhållbarhet. Skapa hjälpfunktioner eller klasser för att hantera kontextdata.
• Tänk på felhantering: Implementera felhantering för att elegant hantera fall där AsyncLocalStorage inte är korrekt initierat.
• Testa noggrant: Skriv enhets- och integrationstester för att säkerställa att kontextpropageringen fungerar som förväntat.
• Dokumentera användning: Dokumentera tydligt hur AsyncLocalStorage används i din applikation för att hjälpa andra utvecklare att förstå kontextpropageringsmekanismen.

Integration med OpenTelemetry

OpenTelemetry är ett ramverk för observerbarhet med öppen källkod som tillhandahåller API:er, SDK:er och verktyg för att samla in och exportera telemetridata (t.ex. spårningar, mätvärden, loggar). AsyncLocalStorage kan sömlöst integreras med OpenTelemetry för att automatiskt propagera spårningskontext över asynkrona operationer.

OpenTelemetry förlitar sig i hög grad på kontextpropagering för att korrelera spårningar över olika tjänster. Genom att använda AsyncLocalStorage kan du säkerställa att spårningskontexten propageras korrekt inom din Node.js-applikation, vilket gör att du kan bygga ett omfattande distribuerat spårningssystem.

Många OpenTelemetry SDK:er använder automatiskt AsyncLocalStorage (eller cls-hooked om AsyncLocalStorage inte är tillgängligt) för kontextpropagering. Kontrollera dokumentationen för ditt valda OpenTelemetry SDK för specifika detaljer.

Slutsats

AsyncLocalStorage är ett värdefullt verktyg för att hantera asynkron kontextpropagering i server-side JavaScript-applikationer. Genom att använda det för request-spårning, autentisering, loggning och andra användningsfall kan du bygga mer robusta, observerbara och underhållbara applikationer. Även om alternativ som cls-hooked och Async Hooks existerar, är AsyncLocalStorage generellt det föredragna valet på grund av att det är inbyggt, dess prestanda och användarvänlighet. Kom ihåg att följa bästa praxis och vara medveten om dess begränsningar för att effektivt utnyttja dess kapacitet. Förmågan att spåra anrop och korrelera händelser över asynkrona operationer är avgörande för att bygga skalbara och pålitliga system, särskilt i microservices-arkitekturer och komplexa distribuerade miljöer. Att använda AsyncLocalStorage hjälper till att uppnå detta mål, vilket i slutändan leder till bättre felsökning, prestandaövervakning och övergripande applikationshälsa.